/*
 * Javlov - a Java toolkit for reinforcement learning with multi-agent support.
 * 
 * Copyright (c) 2009 Matthijs Snel
 * 
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
package net.javlov;

/**
 * A policy that maps states to actions.
 * 
 * @author Matthijs Snel
 *
 */
public interface Policy {

	/**
	 * Returns an action based on a state.
	 * 
	 * @param s the state based on which to choose an action.
	 * @return the action.
	 */
	public <T> Action getAction(State<T> s);
	
	/**
	 * Returns an action based on Q-values (optional operation). A large number of policies
	 * will determine which action to take by querying the Q-function for the Q-values of
	 * the state, and based on those values choose an action. This method is provided to
	 * avoid having to query the Q-function multiple times, since learning agents also need
	 * to query the Q-function on every step.
	 * 
	 * This operation is optional since policies that directly map states to actions, such
	 * as in actor-critic methods, won't be able to implement it.
	 * 
	 * @param qvalues the Q-values of all actions for the state based on which an action
	 * should be chosen.
	 * @return the action.
	 * @throws UnsupportedOperationException if the operation is not supported by this
	 * policy.
	 */
	public Action getAction( double[] qvalues );
}
